<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>Chapter 2. Database Environments</title>
    <link rel="stylesheet" href="gettingStarted.css" type="text/css" />
    <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
    <link rel="start" href="index.html" title="Getting Started with Berkeley DB Java Edition" />
    <link rel="up" href="index.html" title="Getting Started with Berkeley DB Java Edition" />
    <link rel="prev" href="logfilesrevealed.html" title="Six Things Everyone Should Know about JE Log Files" />
    <link rel="next" href="envclose.html" title="Closing Database Environments" />
  </head>
  <body>
    <div class="navheader">
      <table width="100%" summary="Navigation header">
        <tr>
          <th colspan="3" align="center">Chapter 2. Database Environments</th>
        </tr>
        <tr>
          <td width="20%" align="left"><a accesskey="p" href="logfilesrevealed.html">Prev</a> </td>
          <th width="60%" align="center"> </th>
          <td width="20%" align="right"> <a accesskey="n" href="envclose.html">Next</a></td>
        </tr>
      </table>
      <hr />
    </div>
    <div class="chapter" lang="en" xml:lang="en">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title"><a id="env"></a>Chapter 2. Database Environments</h2>
          </div>
        </div>
      </div>
      <div class="toc">
        <p>
          <b>Table of Contents</b>
        </p>
        <dl>
          <dt>
            <span class="sect1">
              <a href="env.html#envopen">Opening Database Environments</a>
            </span>
          </dt>
          <dd>
            <dl>
              <dt>
                <span class="sect2">
                  <a href="env.html#multienv">Multiple Environments</a>
                </span>
              </dt>
              <dt>
                <span class="sect2">
                  <a href="env.html#multienvsharedcache">Configuring a Shared Cache for Multiple Environments</a>
                </span>
              </dt>
            </dl>
          </dd>
          <dt>
            <span class="sect1">
              <a href="envclose.html">Closing Database Environments</a>
            </span>
          </dt>
          <dt>
            <span class="sect1">
              <a href="EnvProps.html">Environment Properties</a>
            </span>
          </dt>
          <dd>
            <dl>
              <dt>
                <span class="sect2">
                  <a href="EnvProps.html#envconfig">The EnvironmentConfig Class</a>
                </span>
              </dt>
              <dt>
                <span class="sect2">
                  <a href="EnvProps.html#envhandleconfig">EnvironmentMutableConfig</a>
                </span>
              </dt>
            </dl>
          </dd>
          <dt>
            <span class="sect1">
              <a href="envStats.html">Environment Statistics</a>
            </span>
          </dt>
          <dt>
            <span class="sect1">
              <a href="dbenvUsageExample.html">Database Environment Management Example</a>
            </span>
          </dt>
        </dl>
      </div>
      <p>
        Regardless of whether you are using the DPL or the base API, you must use a database
        environment.  Database environments encapsulate one or more databases. This encapsulation
        provides your threads with efficient access to your databases by allowing a single in-memory
        cache to be used for each of the databases contained in the environment. This encapsulation
        also allows you to group operations performed against multiple databases inside a single
        transactions (see the <em class="citetitle">Berkeley DB, Java Edition Getting Started with Transaction Processing</em> guide for more information).
  </p>
      <p>
        If you are using the base API, most commonly you use database environments to create and
        open databases (you close individual databases using the individual database handles). You
        can also use environments to delete and rename databases. For transactional applications,
        you use the environment to start transactions. For non-transactional applications, you use
        the environment to sync your in-memory cache to disk.
 </p>
      <p>
         If you are using the DPL, all of these things are still being done, but the DPL takes
         care of it for you. Under the DPL, the most common thing you will explicitly use an
         environment for is to obtain transaction handles.
 </p>
      <p>

         Regardless of the API that you use, you also use the database environment for
         administrative and configuration activities related to your database log files and the
         in-memory cache. 
    
         See <a class="xref" href="administration.html" title="Chapter 12. Administering Berkeley DB Java Edition Applications">Administering Berkeley DB Java Edition Applications</a> for
         more information.
 </p>
      <p>
    To find out how to use environments with a transaction-protected application, see the
    <em class="citetitle">Berkeley DB, Java Edition Getting Started with Transaction Processing</em> guide.
  </p>
      <div class="sect1" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h2 class="title" style="clear: both"><a id="envopen"></a>Opening Database Environments</h2>
            </div>
          </div>
        </div>
        <div class="toc">
          <dl>
            <dt>
              <span class="sect2">
                <a href="env.html#multienv">Multiple Environments</a>
              </span>
            </dt>
            <dt>
              <span class="sect2">
                <a href="env.html#multienvsharedcache">Configuring a Shared Cache for Multiple Environments</a>
              </span>
            </dt>
          </dl>
        </div>
        <p>
            You open a database environment by instantiating an <code class="classname">Environment</code>
            object. You must provide to the constructor the name of the on-disk directory where the
            environment is to reside.  This directory location must exist or the open will fail.
    </p>
        <p>
            By default, the environment is not created for you if it does not exist. Set the <a class="link" href="EnvProps.html" title="Environment Properties">creation property</a> to <code class="literal">true</code> if you
            want the environment to be created. For example:
    </p>
        <pre class="programlisting">package je.gettingStarted;
    
import com.sleepycat.je.DatabaseException;
import com.sleepycat.je.Environment;
import com.sleepycat.je.EnvironmentConfig;

import java.io.File;

...

// Open the environment. Allow it to be created if it does not 
// already exist.
Environment myDbEnvironment = null;

try {
    EnvironmentConfig envConfig = new EnvironmentConfig();
    envConfig.setAllowCreate(true);
    myDbEnvironment = new Environment(new File("/export/dbEnv"), 
                                      envConfig);
} catch (DatabaseException dbe) {
    // Exception handling goes here
} </pre>
        <p>
            Opening an environment usually causes some background threads to be started. JE uses
            these threads for log file cleaning and some administrative tasks. However, these
            threads will only be opened once per process, so if you open the same environment more
            than once from within the same process, there is no performance impact on your
            application.  Also, if you open the environment as read-only, then the background
            threads (with the exception of the evictor thread) are not started.
    </p>
        <p>
        Note that opening your environment causes normal recovery to be run. This
        causes your databases to be brought into a consistent state relative to the
        changed data found in your log files. 
        See <a class="xref" href="backuprestore.html#databaselogs" title="Databases and Log Files">Databases and Log Files</a> 
        for more information.
    </p>
        <div class="sect2" lang="en" xml:lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h3 class="title"><a id="multienv"></a>Multiple Environments</h3>
              </div>
            </div>
          </div>
          <p>
                    Most JE applications only need a single database environment because any
                    number of databases can be created in a single environment, and the
                    total size of the data in an environment is not limited. That said, 
                    your application can open and use as many environments as you have disk and
                    memory to manage.  Also, you can instantiate 
                    multiple <code class="classname">Environment</code> objects
                    for the same physical environment.
            </p>
          <p>
                    The main reason for multiple environments is that an application must manage
                    multiple unique data sets. By placing each data set in a separate environment,
                    the application can gain real advantages in manageability of the data, and with
                    application performance. By placing each data set in a unique environment,
                    a separate set of log files is created and maintained in a separate directory,
                    and so you can manipulate the log files for each data set separately. 
                    That is, you can:
            </p>
          <div class="itemizedlist">
            <ul type="disc">
              <li>
                <p>
                                    Backup, restore or delete a single data set
                                    separately by copying or removing the files for its environment.
                            </p>
              </li>
              <li>
                <p>
                                    Balance the load between machines by moving the files for a
                                    single data set from one machine to another.
                            </p>
              </li>
              <li>
                <p>
                                    Improve I/O performance by placing each data set on a separate
                                    physical disk.
                            </p>
              </li>
              <li>
                <p>
                                    Delete individual data sets very efficiently by removing the
                                    environment's log files. This is much more efficient than
                                    deleting individual database records and is also move
                                    efficient than removing databases, and so can be a real benefit
                                    if you are managing large  temporary data sets that must be
                                    frequently deleted.
                            </p>
              </li>
            </ul>
          </div>
          <p>
                    Be aware that there is a downside to using multiple environments. In particular,
                    understand that a single transaction cannot include changes
                    made in more than one environment.  If you need to perform a set of
                    operations in more than one data set atomically (with a single
                    transaction), use a single environment and distinguish the data sets
                    using some other method.
            </p>
          <p>
                    For example, an application running a hosted service for multiple clients may
                    wish to keep each client's data set separate. You can do this with multiple
                    environments, but then you can operate on all data sets atomically. If you need
                    to wrap operations for multiple data sets in a single transaction, consider some
                    other approach to keeping the data sets separate.
            </p>
          <p>
                    You can, for example, distinguish each data set using a unique key range within
                    a single database. Or you can create a secondary key that identifies the data
                    set. Or you could use separate databases for each dataset. All of these
                    approaches allow you to maintain multiple distinct dataset within a single
                    environment, but each obviously adds a level of complexity to your code over
                    what is required to simply use a unique environment for each data set.
            </p>
        </div>
        <div class="sect2" lang="en" xml:lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h3 class="title"><a id="multienvsharedcache"></a>Configuring a Shared Cache for Multiple Environments</h3>
              </div>
            </div>
          </div>
          <p>
                    By default, each distinct JE environment has a separate, private
                    in-memory cache.  If a single JVM process will keep open multiple
                    environments at the same time, it is strongly recommended that all such
                    environments are configured to use a shared cache.  A shared cache makes
                    much more efficient use of memory than separate private caches.
            </p>
          <p>
                    For example, imagine that you open 5 environments in a single process
                    and a total of 500 MB of memory is available for caching.  Using private
                    caches, you could configure each cache to be 100 MB.  If one of the
                    environments has a larger active data set than the others, it will
                    not be able to take advantage of unused memory in the other environment
                    caches.  By using a shared cache, multiple open environments will make
                    better use of memory because the cache LRU algorithm is applied across
                    all information in all enviornments sharing the cache.
            </p>
          <p>
                    In order to configure an environment to use a shared cache, set
                    <code class="methodname">EnvironmentConfig.setSharedCache()</code>
                    to <code class="literal">true</code>. This must be set for every environment in the
                    process that you want to use the shared cache. For example:
            </p>
          <pre class="programlisting">package je.gettingStarted;
    
import com.sleepycat.je.DatabaseException;
import com.sleepycat.je.Environment;
import com.sleepycat.je.EnvironmentConfig;

import java.io.File;

...

// Open the environment. Allow it to be created if it does not 
// already exist.
Environment myEnv1 = null;
Environment myEnv2 = null;

try {
    EnvironmentConfig envConfig = new EnvironmentConfig();
    envConfig.setAllowCreate(true);
    envConfig.setSharedCache(true);

    myEnv1 = new Environment(new File("/export/dbEnv1"), envConfig);
    myEnv2 = new Environment(new File("/export/dbEnv2"), envConfig);
} catch (DatabaseException dbe) {
    // Exception handling goes here
} </pre>
        </div>
      </div>
    </div>
    <div class="navfooter">
      <hr />
      <table width="100%" summary="Navigation footer">
        <tr>
          <td width="40%" align="left"><a accesskey="p" href="logfilesrevealed.html">Prev</a> </td>
          <td width="20%" align="center"> </td>
          <td width="40%" align="right"> <a accesskey="n" href="envclose.html">Next</a></td>
        </tr>
        <tr>
          <td width="40%" align="left" valign="top">Six Things Everyone Should Know about JE Log Files </td>
          <td width="20%" align="center">
            <a accesskey="h" href="index.html">Home</a>
          </td>
          <td width="40%" align="right" valign="top"> Closing Database Environments</td>
        </tr>
      </table>
    </div>
  </body>
</html>
